package com.ksyun.campus.metaserver.storage;

import com.ksyun.campus.metaserver.domain.*;

import java.util.List;
import java.util.Optional;

/**
 * Metadata storage interface
 * 元数据存储接口，定义了文件系统元数据的存储和检索操作
 * 包括inode、目录项、路径缓存、块信息和DataServer信息的管理
 */
public interface MetadataStore {
    
    /**
     * 启动元数据存储服务
     * 初始化存储引擎和相关资源
     */
    void start() throws Exception;
    
    /**
     * 停止元数据存储服务
     * 释放资源并确保数据持久化
     */
    void stop() throws Exception;
    
    /**
     * 存储inode信息
     * 
     * @param inode 要存储的inode对象
     */
    void putInode(Inode inode) throws Exception;
    
    /**
     * 获取指定fileId的inode信息
     * 
     * @param fileId 文件ID
     * @return 包含inode的Optional对象，如果不存在则为empty
     */
    Optional<Inode> getInode(String fileId) throws Exception;
    
    /**
     * 删除指定fileId的inode信息
     * 
     * @param fileId 要删除的文件ID
     */
    void deleteInode(String fileId) throws Exception;
    
    /**
     * 存储目录项信息，建立父目录与子文件/目录的关联
     * 
     * @param parentId 父目录ID
     * @param name 文件或目录名称
     * @param fileId 文件或目录ID
     */
    void putDentry(String parentId, String name, String fileId) throws Exception;
    
    /**
     * 获取目录项信息，查找指定父目录下特定名称的文件或目录ID
     * 
     * @param parentId 父目录ID
     * @param name 文件或目录名称
     * @return 包含文件ID的Optional对象，如果不存在则为empty
     */
    Optional<String> getDentry(String parentId, String name) throws Exception;
    
    /**
     * 删除目录项信息
     * 
     * @param parentId 父目录ID
     * @param name 要删除的文件或目录名称
     */
    void deleteDentry(String parentId, String name) throws Exception;
    
    /**
     * 列出指定目录下的所有文件和子目录名称
     * 
     * @param parentId 父目录ID
     * @return 文件和子目录名称列表
     */
    List<String> listDentries(String parentId) throws Exception;
    
    /**
     * 存储路径到文件ID的映射，用于路径解析缓存
     * 
     * @param path 文件系统路径
     * @param fileId 对应的文件ID
     */
    void putPathCache(String path, String fileId) throws Exception;
    
    /**
     * 获取路径对应的文件ID，用于快速路径解析
     * 
     * @param path 文件系统路径
     * @return 包含文件ID的Optional对象，如果不存在则为empty
     */
    Optional<String> getPathCache(String path) throws Exception;
    
    /**
     * 删除路径缓存
     * 
     * @param path 要删除缓存的文件系统路径
     */
    void deletePathCache(String path) throws Exception;
    
    /**
     * 存储文件块信息
     * 
     * @param fileId 文件ID
     * @param blkIdx 块索引
     * @param blockInfo 块信息对象
     */
    void putBlock(String fileId, int blkIdx, BlockInfo blockInfo) throws Exception;
    
    /**
     * 获取指定文件的特定块信息
     * 
     * @param fileId 文件ID
     * @param blkIdx 块索引
     * @return 包含块信息的Optional对象，如果不存在则为empty
     */
    Optional<BlockInfo> getBlock(String fileId, int blkIdx) throws Exception;
    
    /**
     * 删除指定文件的特定块信息
     * 
     * @param fileId 文件ID
     * @param blkIdx 块索引
     */
    void deleteBlock(String fileId, int blkIdx) throws Exception;
    
    /**
     * 获取指定文件的所有块信息
     * 
     * @param fileId 文件ID
     * @return 块信息列表
     */
    List<BlockInfo> getFileBlocks(String fileId) throws Exception;
    
    /**
     * 获取系统中所有块信息，用于FSCK和系统恢复
     * 
     * @return 所有块信息的列表
     */
    List<BlockInfo> getAllBlocks() throws Exception;
    
    /**
     * 存储DataServer信息
     * 
     * @param dsInfo DataServer信息对象
     */
    void putDataServer(DataServerInfo dsInfo) throws Exception;
    
    /**
     * 获取指定ID的DataServer信息
     * 
     * @param dsId DataServer ID
     * @return 包含DataServer信息的Optional对象，如果不存在则为empty
     */
    Optional<DataServerInfo> getDataServer(String dsId) throws Exception;
    
    /**
     * 删除指定ID的DataServer信息
     * 
     * @param dsId DataServer ID
     */
    void deleteDataServer(String dsId) throws Exception;
    
    /**
     * 获取所有DataServer信息
     * 
     * @return DataServer信息列表
     */
    List<DataServerInfo> getAllDataServers() throws Exception;
    
    /**
     * 存储集群配置信息
     * 
     * @param config 集群配置对象
     */
    void putClusterConfig(ClusterConfig config) throws Exception;
    
    /**
     * 获取集群配置信息
     * 
     * @return 包含集群配置的Optional对象，如果不存在则为empty
     */
    Optional<ClusterConfig> getClusterConfig() throws Exception;
    
    /**
     * 获取系统中所有Inode的总数
     * 
     * @return Inode总数
     */
    long getTotalInodeCount() throws Exception;
    
    /**
     * 获取系统中所有Block的总数
     * 
     * @return Block总数
     */
    long getTotalBlockCount() throws Exception;
    
    /**
     * 获取系统中所有Inode信息
     * 
     * @return 所有Inode的列表
     */
    List<Inode> getAllInodes() throws Exception;
    
    /**
     * 根据fileId获取对应的路径
     * 
     * @param fileId 文件ID
     * @return 文件路径，如果不存在则返回null
     */
    String getInodePath(String fileId) throws Exception;
    
    /**
     * 清空所有元数据（用于从节点重置）
     */
    void clearAllData() throws Exception;
}
